home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / swagg_m.zip / MAIL.SWG / 0004_QWKMAIL.PAS.pas < prev    next >
Pascal/Delphi Source File  |  1993-05-28  |  37KB  |  850 lines
  1.                          QWK Mail Packet File Layout
  2.                               by Patrick Y. Lee
  3.                        Version 1.0 - February 23, 1992
  4.  
  5. This document is Copyright 1992 by Patrick Y. Lee.
  6.  
  7. The QWK-format is Copyright 1987 by Sparkware.
  8.  
  9. All Program names mentioned in this document are either Copyright
  10. or Trade- mark of respective owner(s).
  11.  
  12. The author provides this File as-is without warranty of any kind,
  13. either expressed or implied.  You are using the information in
  14. this File at your own discretion.  The author assumes no
  15. responsibilities For damages, either physically or financially,
  16. from the use of this information.
  17.  
  18. This document may be freely distributed by any means
  19. (electronically, pa- per, etc.), provided that it is distributed
  20. in its entirety.  Portions of this document may be reproduced
  21. without credit.
  22.  
  23.                               Table of Contents
  24.  
  25. 1.  Introduction
  26.     1.1.  Intent
  27.     1.2.  History
  28.     1.3.  Questions, corrections, etc.
  29. 2.  Conventions & overview
  30.     2.1.  The BBS ID
  31.     2.2.  Packet compression
  32.     2.3.  Packet transfer & protocols
  33.     2.4.  Limitations
  34. 3.  QWK Files
  35.     3.1.  Naming convention
  36.     3.2.  Control File (CONTROL.DAT)
  37.     3.3.  Welcome File
  38.     3.4.  Goodbye File
  39.     3.5.  News File
  40.     3.6.  Qmail DeLuxe menu File
  41.     3.7.  New uploads listing (NEWFileS.DAT)
  42.     3.8.  Bulletin File(s) (BLT-x.y)
  43.     3.9.  Message File (MESSAGES.DAT)
  44.     3.10.  Index Files (*.NDX)
  45.         3.10.1.  Conference indices
  46.         3.10.2.  Personal index (PERSONAL.NDX)
  47.     3.11.  Pointer File
  48.     3.12.  SESSION.TXT
  49. 4.  REP Files
  50.     4.1.  Naming convention
  51.     4.2.  Message File (BBSID.MSG)
  52.     4.3.  Door control messages
  53.     4.3.1.  DOOR.ID File
  54.     4.3.2.  Qmail
  55.     4.3.3.  MarkMail
  56.     4.3.4.  KMail
  57.     4.3.5.  RoseMail
  58.     4.3.6.  Complete Mail Door
  59.     4.4.  Turning off the echo flag
  60.     4.5.  Tag-lines
  61. 5.  Net mail
  62. A.  Credits & contributions
  63. B.  Sample Turbo Pascal and C code
  64. C.  Sample message
  65. D.  Sample index File
  66.  
  67.                         -=-=-=-=-=-=-<>-=-=-=-=-=-=-
  68.  
  69. To search For a specific section, look For "[x.x]" using your
  70. editor or viewer.  For example, to jump to the tag-lines portion
  71. of this File, search For "[4.5]" With your editor or Text viewer.
  72.  
  73.                         -=-=-=-=-=-=-<>-=-=-=-=-=-=-
  74.  
  75. [1]  Introduction
  76.  
  77. [1.1]  Intent
  78.  
  79. This document is written to facilitate Programmers who want to
  80. Write QWK-format mail doors or readers.  It is intended to be a
  81. comprehen- sive reference covering all areas of QWK-format mail
  82. processing.  De- tailed break down of each File is included, as
  83. are Implementation information.  In addition, door and reader
  84. specific information may be included, when such information are
  85. available to me.
  86.  
  87. [1.2]  History
  88.  
  89. The QWK-format was invented by Mark "Sparky" Herring in 1987.  It
  90. was based on Clark Development Corporation's PCBoard version 12.0
  91. message base format.  Off-line mail reading has become popular
  92. only in recent years.  Prior to summer of 1990, there were only
  93. two QWK-format off- line mail reader Programs.  They were Qmail
  94. DeLuxe by Mark Herring and EZ-Reader by Eric Cockrell.  Similarly
  95. for the doors, there were only two -- Qmail by Mark Herring and
  96. MarkMail by Mark Turner.  They were both For PCBoard systems.
  97.  
  98. A lot has changed in both off-line reader and mail door markets
  99. since summer 1990.  Now, there are more than a dozen off-line
  100. mail readers For the PC.  Readers For the Macintosh, Amiga, and
  101. Atari exist as well.  There are over a half dozen doors for
  102. PCBoard, and QWK-format doors exist For virtually all of the
  103. popular BBS softwares.  All of these happened in less than two
  104. years!  More readers and doors are in development as I Write
  105. this, keep up the excellent work.  In addition to doors, some BBS
  106. softwares has QWK-format mail facility built in.
  107.  
  108. Off-line mail reading is an integral part of BBS calling.
  109. Conference traffic and selection on all networks have grown
  110. dramatically in re- cent years that on-line reading is a thing of
  111. the past.  Off-line mail reading offers an alternative to reading
  112. mail on-line -- It offers speed that cannot be achieved with
  113. on-line mail reading.
  114.  
  115. The reason why QWK-format readers and doors seem to have gained
  116. popu- larity is probably dued to its openness.  The format is
  117. readily avail- able to any Programmer who wishes to Write a
  118. Program that utilize it. Proprietary is a thing of the past, it
  119. does not work!  Openness is here to stay and QWK-format is a part
  120. of it.
  121.  
  122. [1.3]  Questions, corrections, etc.
  123.  
  124. Most of the message networks today have a conference/echo devoted
  125. to discussion of off-line readers and mail doors.  The ones I
  126. know are on FidoNet, ILink, Intelec, and RIME.  If you have
  127. questions after read- ing anything in here, feel free to drop by
  128. any of the above confer- ence/echo and I am sure other QWK
  129. authors will try to help.
  130.  
  131. I can be reached in the Off-line conferences on RIME, ILink, and
  132. Intelec, as well as the Common conference on RIME.  Mail can be
  133. routed to node RUNNINGB.  I can be reached on the Internet at
  134. "p.lee@green.cooper.edu".  Any corrections, extensions, comments,
  135. and criticisms are welcomed.
  136.  
  137. [2]  Conventions & overview
  138. All offsets referenced in this document will be relative to 1.  I
  139. am not a computer, I start counting at one, not zero!
  140.  
  141. Words which are enclosed in quotes should be entered as-is.  The
  142. quo- tations are not part of the String unless noted.
  143.  
  144. You may have noticed I use the phrase "mail Program" or "mail
  145. facili- ty" instead of mail doors.  This is because some BBS
  146. softwares offer the option of creating QWK-format mail packets
  147. right from the BBS. With those, there is no need For an external
  148. mail door.
  149.  
  150. [2.1]  The BBS ID
  151.  
  152. The BBS ID (denoted as BBSID) is a 1-8 Characters Word that
  153. identifies a particular BBS.  This identifier should be obtained
  154. from line 5 of the CONTROL.DAT File (see section 3.2.1).
  155.  
  156. [2.2]  Packet compression
  157.  
  158. Most mail packets are compressed when created by the mail door in
  159. order to save download time and disk space.  However, many
  160. off-line reader Programs allow the user to unarchive a mail
  161. packet outside of the reader Program, so the reader will not have
  162. to unarchive it.  Upon Exit, the reader will not call the
  163. archiver to save it.  It is up to the user to archive the
  164. replies.  This is useful if the user has lim- ited memory and
  165. cannot shell out to Dos to run the unarchive Program. For readers
  166. based on non-PC equipment, the user may be using less common
  167. compression Program that does not have command line equivalent.
  168.  
  169. [2.3]  Packet transfer & protocols
  170.  
  171. There is no set rule on what transfer protocol should be used.
  172. Howev- er, it would be nice For the mail Program on the BBS to
  173. provide the Sysop With options as to what to offer.  This should
  174. be a configura- tion option For the user.
  175.  
  176. [2.4]  Specifications & limitations
  177.  
  178. There aren't many known limits in the QWK specification.
  179. However, Various networks seem to impose artificial limits.  On
  180. many of the PC- based networks, 99-lines appears to be the upper
  181. limit For some softwares.  However, most of the readers can
  182. handle more than that. Reader authors reading this may want to
  183. offer the option to split replies into n lines each (the actual
  184. length should be user definable so when the network software
  185. permits, the user can increase this num- ber).
  186.  
  187. [3]  QWK Files
  188.  
  189. [3.1]  Naming convention
  190.  
  191. Generally, the name of the mail packet is BBSID.QWK.  However,
  192. this does not have to be the case.  When the user downloads more
  193. than one mail packet at one time, either the mail Program or the
  194. transfer pro- tocol Program will rename the second and subsequent
  195. mail packets to other names.  They will either change the File
  196. extension or add a number to the end of the Filename.  In either
  197. case, you should not rely on the name of the QWK File as the
  198. BBSID.  The BBSID, as men- tioned before, should be obtained from
  199. line 5 of the CONTROL.DAT File. In addition, mail packets do not
  200. have to end With QWK extension ei- ther.  The user may choose to
  201. name them With other File extensions.
  202.  
  203. [3.2]  Control File (CONTROL.DAT)
  204.  
  205. The CONTROL.DAT File is a simple ASCII File.  Each line is
  206. terminated With a carriage return and line feed combination.  All
  207. lines should start on the first column.
  208.  
  209. Line #
  210.  1   My BBS                   BBS name
  211.  2   New York, NY             BBS city and state
  212.  3   212-555-1212             BBS phone number
  213.  4   John Doe, Sysop          BBS Sysop name
  214.  5   20052,MYBBS              Mail door registration #, BBSID
  215.  6   01-01-1991,23:59:59      Mail packet creation time
  216.  7   JANE DOE                 User name (upper case)
  217.  8                            Name of menu For Qmail, blank if none
  218.  9   0                        ? Seem to be always zero
  219. 10   0                        ? Seem to be always zero
  220. 11   121                      Total number of conference minus 1
  221. 12   0                        1st conf. number
  222. 13   Main Board               1st conf. name (13 Characters or less)
  223. 14   1                        2nd conf. number
  224. 15   General                  2nd conf. name
  225. ..   3                        etc. onward Until it hits max. conf.
  226. ..   123                      Last conf. number
  227. ..   Amiga_I                  Last conf. name
  228. ..   HELLO                    Welcome screen File
  229. ..   NEWS                     BBS news File
  230. ..   SCRIPT0                  Log off screen
  231.  
  232. Some mail doors, such as MarkMail, will send additional
  233. information about the user from here on.
  234.  
  235. 0                             ?
  236. 25                            Screen length on the BBS
  237. JANE DOE                      User name in uppercase
  238. Jane                          User first name in mixed case
  239. NEW YORK, NY                  User city information
  240. 718 555-1212                  User data phone number
  241. 718 555-1212                  User home phone number
  242. 108                           Security level
  243. 00-00-00                      Expiration date
  244. 01-01-91                      Last log on date
  245. 23:59                         Last log on time
  246. 999                           Log on count
  247. 0                             Current conference number on the BBS
  248. 0                             Total KB downloaded
  249. 999                           Download count
  250. 0                             Total KB uploaded
  251. 999                           Upload count
  252. 999                           Minutes per day
  253. 999                           Minutes remaining today
  254. 999                           Minutes used this call
  255. 32767                         Max. download KB per day
  256. 32767                         Remaining KB today
  257. 0                             KB downloaded today
  258. 23:59                         Current time on BBS
  259. 01-01-91                      Current date on BBS
  260. My BBS                        BBS network tag-line
  261. 0                             ?
  262.  
  263. Some mail doors will offer the option of sending an abbreviated
  264. con- ference list.  That means the list will contain only
  265. conferences the user has selected.  This is done because some
  266. mail readers cannot handle more than n conferences at this time.
  267. Users using those read- ers will need this option if the BBS they
  268. call have too many confer- ences.
  269.  
  270. [3.3]  Welcome File
  271.  
  272. This File usually contains the log on screen from the BBS.  The
  273. exact Filename is specified in the CONTROL.DAT File, after the
  274. conference list.  This File may be in any format the Sysop
  275. chooses it be -- usu- ally either in plain ASCII or With ANSI
  276. screen control code.  Some Sysops (notably PCBoard Sysops) may
  277. use BBS-specific color change code in this File as well.  Current
  278. mail Programs seem to handle the trans- lations between
  279. BBS-specific code to ANSI based screen control codes.
  280. Even if the CONTROL.DAT File contains the Filename of this File,
  281. it may not actually exist in the mail packet.  Sometimes, users
  282. will manually delete this File before entering the mail reader.
  283. Some off- line readers offer the option to not display this
  284. welcome screen; some will display this File regardless.  Some
  285. doors, similarly, will offer option to the user to not send this
  286. File.
  287.  
  288. [3.4]  Goodbye File
  289.  
  290. Similar to the welcome File above, the Filename to the goodbye
  291. File is in the CONTROL.DAT File.  This is the File the BBS
  292. displays when the user logs off the board.  It is optional, as
  293. always, to send this File or to display it.
  294.  
  295. [3.5]  News File
  296.  
  297. Many mail doors offer the option to send the news File from the
  298. BBS. Most will only send this when it has been updated.  Like the
  299. welcome and goodbye Files, the Filename to the news File is found
  300. in the CON- TROL.DAT File.  It can be in any format the Sysop
  301. chooses, but usually in either ASCII or ANSI.  Like the welcome
  302. screen, current mail facil- ities seem to handle translation
  303. between BBS-specific control codes to ANSI screen control codes.
  304.  
  305. [3.6]  Qmail DeLuxe menu File
  306.  
  307. This File is of use only For Qmail DeLuxe mail reader by
  308. Sparkware. The Filename is found on line 8 of the CONTROL.DAT
  309. File.
  310.  
  311. [3.7]  New uploads listing (NEWFileS.DAT)
  312.  
  313. Most mail Programs on the BBS will offer the option to scan new
  314. Files uploaded to the BBS.  The result is found in a File named
  315. NEWFileS.DAT.  The mail Program, if implementing this, should
  316. update the last File scan field in the user's proFile, if there
  317. is such a field, as well as other information required by the
  318. BBS.  The mail Program should, of course, scan new Files only in
  319. those areas the user is allowed access.
  320.  
  321. [3.8]  Bulletin Files (BLT-x.y)
  322.  
  323. Most mail Programs will also offer the option to include updated
  324. bul- letin Files found on the BBS in the mail packet.  The
  325. bulletins are named BLT-x.y, where x is the conference/echo the
  326. bulletin came from, and y the bulletin's actual number.  The mail
  327. Program will have to take care of updating the last read date on
  328. the bulletins in the user Record.
  329.  
  330. [3.9]  Message File (MESSAGES.DAT)
  331.  
  332. The MESSAGES.DAT File is the most important.  This is where all
  333. of the messages are contained in.  The QWK File format is based
  334. on PCBoard 12.0 message base format from Clark Development
  335. Corporation (maker of PCBoard BBS software).
  336.  
  337. The File has a logical Record length of 128-Bytes.  The first
  338. Record of MESSAGES.DAT always contain a copyright notice saying
  339. "Produced by Qmail...Copyright (c) 1987 by Sparkware.  All Rights
  340. Reserved".  The rest of the Record is space filled.  Actual
  341. messages consist of a 128- Bytes header, plus one or more
  342. 128-Bytes block With the message Text. Actual messages start in
  343. Record 2.  The header block is layed out as follows:
  344.  
  345. Offset  Length  Description
  346. ------  ------  ----------------------------------------------------
  347.     1       1   Message status flag (unsigned Character)
  348.                 ' ' = public, unread
  349.                 '-' = public, read
  350.                 '+' = private, unread
  351.                 '*' = private, read
  352.                 '~' = comment to Sysop, unread
  353.                 '`' = comment to Sysop, read
  354.                 '%' = passWord protected, unread
  355.                 '^' = passWord protected, read
  356.                 '!' = group passWord, unread
  357.                 '#' = group passWord, read
  358.                 '$' = group passWord to all
  359.     2       7   Message number (in ASCII)
  360.     9       8   Date (mm-dd-yy, in ASCII)
  361.    17       5   Time (24 hour hh:mm, in ASCII)
  362.    22      25   To (uppercase, left justified)
  363.    47      25   From (uppercase, left justified)
  364.    72      25   Subject of message (mixed case)
  365.    97      12   PassWord (space filled)
  366.   109       8   Reference message number (in ASCII)
  367.   117       6   Number of 128-Bytes blocks in message (including the
  368.                 header, in ASCII; the lowest value should be 2, header
  369.                 plus one block message; this number may not be left
  370.                 flushed within the field)
  371.   123       1   Flag (ASCII 225 means message is active; ASCII 226
  372.                 means this message is to be killed)
  373.   124       2   Conference number (unsigned Word)
  374.   126       2   Not used (usually filled With spaces or nulls)
  375.   128       1   Indicates whether the message has a network tag-line
  376.                 or not.  A value of '*' indicates that a network tag-
  377.                 line is present; a value of ' ' (space) indicates
  378.                 there isn't one.  Messages sent to readers (non-net-
  379.                 status) generally leave this as a space.  Only network
  380.                 softwares need this information.
  381.  
  382. Fields such as To, From, Subject, Message #, Reference #, and the
  383. like are space padded if they are shorter than the field's
  384. length.
  385.  
  386. The message Text starts in the next Record.  You can find out how
  387. many blocks make up one message by looking at the value of
  388. "Number of 128 Byte blocks".  Instead of carriage return and line
  389. feed combination, each line in the message end With an ASCII 227
  390. (pi Character) symbol. There are reports that some (buggy)
  391. readers have problems With mes- sages which do not end the last
  392. line in the message With an ASCII 227. If a message does not
  393. completely occupy the 128-Bytes block, the re- mainder of the
  394. block is padded With space or null.
  395.  
  396. Note that there seems to exist old doors which will use one Byte
  397. to represent the conference number and pad the other one With an
  398. ASCII 32 Character.  The Program reading this information will
  399. have to deter- mine whether the ASCII 32 in Byte 125 of the
  400. header is a filler or part of the unsigned Word.  One method is
  401. to look in the CONTROL.DAT File to determine the highest
  402. conference number.
  403.  
  404. Even though most mail Programs will generate MESSAGES.DAT Files
  405. that appear in conference order, this is not always the case.
  406. Tomcat! (mail door For Wildcat! BBS) generates MESSAGES.DAT that
  407. is not in conference order.  This is due to how Wildcat! itself
  408. stores mail on the BBS.
  409.  
  410. Note that some mail doors offer the option of sending a mail
  411. packet even though there may be no messages to send -- thus an
  412. empty MESSAG- ES.DAT File.  This was tested With Qmail 4.0 door
  413. and it sent a MES- SAGES.DAT File that contains a few empty
  414. 128-Bytes blocks.
  415.  
  416. [3.10]  Index Files (*.NDX)
  417.  
  418. [3.10.1]  Conference indices
  419.  
  420. The index Files contain a list of Pointers pointing to the
  421. beginning of messages in the MESSAGES.DAT File.  The Pointer is
  422. in terms of the 128-Bytes block logical Record that the
  423. MESSAGES.DAT File is in.  Each conference has its own xxx.NDX
  424. File, where xxx is the conference num- ber left padded with
  425. zeroes.  Some mail Programs offer the user the option to not
  426. generate index Files.  So the mail readers need to cre- ate the
  427. index Files if they are missing.
  428. EZ-Reader 1.xx versions will convert the NDX Files from Microsoft
  429. MKS format into IEEE long Integer format.  The bad part about
  430. this is that the user may store those index Files back into the
  431. QWK File.  When another reader reads the index Files, it will be
  432. very confused!
  433.  
  434. Special note For BBSes With more than 999 conferences: Index
  435. Files For conferences With four digit conference numbers is named
  436. xxxx.NDX, where xxxx is the conference number (left padded with
  437. zeroes).  The Filenames For three digit conferences are still
  438. named xxx.NDX on these boards.  I would assume Filenames for
  439. conferences in the five digit range is xxxxx.NDX, but I have not
  440. seen a BBS With 10,000 or more conferences yet!
  441.  
  442. Each NDX File Uses a five Bytes logical Record length and is
  443. formatted to:
  444.  
  445. Offset  Length  Description
  446. ------  ------  ------------------------------------------------------
  447.     1       4   Record number pointing to corresponding message in
  448.                 MESSAGES.DAT.  This number is in the Microsoft MKS$
  449.                 BASIC format.
  450.     5       1   Conference number of the message.  This Byte should
  451.                 not be used because it duplicates both the Filename of
  452.                 the index File and the conference # in the header.  It
  453.                 is also one Byte long, which is insufficient to handle
  454.                 conferences over 255.
  455.  
  456. Please refer to appendix B For routines to deal With MKS numbers.
  457.  
  458. [3.10.2]  Personal index (PERSONAL.NDX)
  459.  
  460. There is a special index File named PERSONAL.NDX.  This File
  461. contains Pointers to messages which are addressed to the user,
  462. i.e. personal messages.  Some mail door and utility Programs also
  463. allow the selec- tion of other messages to be flagged as personal
  464. messages.
  465.  
  466. [3.11]  Pointer File
  467.  
  468. Pointer File is generally included so that the user can reset the
  469. last read Pointers on the mail Program, in Case there is a crash
  470. on the BBS or some other mishaps.  There should be little reason
  471. for the reader Program to access the Pointer File.
  472.  
  473. The Pointer Files I have seen are:
  474.  
  475. Qmail          BBSID.PTR
  476. MarkMail       BBSID.PNT
  477. KMail          BBSID.PNT
  478. SFMailQwk      BBSID.SFP
  479.  
  480. Additions to this list are welcomed.
  481.  
  482. [3.12]  SESSION.TXT
  483.  
  484. This File, if included, will contain the message scanning screen
  485. the user sees from the door.
  486.  
  487. [4]  REP Files
  488.  
  489. [4.1]  Naming convention
  490.  
  491. The reply File is named BBSID.MSG, where BBSID is the ID code for
  492. the BBS found on line 5 of the CONTROL.DAT File.  Once this File
  493. has been created, the mail reader can archive it up into a File
  494. with REP exten- sion.
  495.  
  496. [4.2]  Message File (BBSID.MSG)
  497.  
  498. Replies use the same format as the MESSAGES.DAT File, except that
  499. mes- sage number field will contain the conference number
  500. instead.  In other Words, the conference number will be placed in
  501. the two Bytes (binary) starting at offset 124, as well as the
  502. message number field (ASCII) at offset 2.
  503.  
  504. The first 128-Bytes Record of the File is the header.  Instead of
  505. the copyright notice, it contains the BBSID of the BBS.  This 1-8
  506. Charac- ter BBSID must start at the very first Byte and must
  507. match what the BBS has.  The rest of the Record is space padded.
  508. The replies start at Record 2.  Each reply message will have a
  509. 128-Bytes header, plus one or more For the message Text; followed
  510. by another header, and so on.
  511.  
  512. The mail Program must check to make sure the BBSID in the first
  513. block of the BBSID.MSG File matches what the BBS has!
  514.  
  515. [4.3]  Door control messages
  516.  
  517. These messages allow the user to change their setup on the BBS by
  518. simply entering a message.  The goal is to allow the user to be
  519. able to control most areas of the BBS via the mail door.
  520. Different mail doors have different capabilities.  Most all of
  521. them offer the ability to add and drop a conference, as well as
  522. reset the last read Pointers in a conference.
  523.  
  524. [4.3.1]  DOOR.ID File
  525.  
  526. The DOOR.ID File was first introduced by Greg Hewgill with
  527. Tomcat! mail door and SLMR mail reader.  Since then, many other
  528. authors have picked up this idea and use the format.  This File
  529. provides the neces- sary identifiers a reader needs to send add,
  530. drop, etc. messages to the mail door.  It tells the reader who to
  531. address the message to and what can be put in the subject line.
  532.  
  533. DOOR = <doorname>             This is the name of the door that creat-
  534.                               ed the QWK packet, i.e. <doorname> =
  535.                               Tomcat.
  536. VERSION = <doorversion>       This is the version number of the door
  537.                               that created the packet, i.e.
  538.                               <doorversion> = 2.9.
  539. SYSTEM = <systemType>         This is the underlying BBS system Type
  540.                               and version, i.e. <systemType> = Wildcat
  541.                               2.55.
  542. CONTROLNAME = <controlname>   This is the name to which the reader
  543.                               should send control messages, eg.
  544.                               <controlname> = TOMCAT.
  545. CONTROLType = <controlType>   This can be one of ADD, DROP, REQUEST,
  546.                               or others.  ADD and DROP are pretty
  547.                               obvious (they work as in MarkMail), and
  548.                               REQUEST is For use With BBS systems that
  549.                               support File attachments.  Try out SLMR
  550.                               With CONTROLType = REQUEST and use the Q
  551.                               Function.  (This seems to be a Wildcat!
  552.                               BBS feature.)
  553. RECEIPT                       This flag indicates that the door/BBS is
  554.                               capable of return receipts when a mes-
  555.                               sage is received.  If the first three
  556.                               letters of the subject are RRR, then the
  557.                               door should strip the RRR and set the
  558.                               'return-receipt-requested' flag on the
  559.                               corresponding message.
  560.  
  561. None of the lines are actually required and they may appear in
  562. any order.  Of course, you would need a CONTROLNAME if you have
  563. any CONTROLType lines.
  564.  
  565. [4.3.2]  Qmail
  566.  
  567. Send a message addressed to "QMAIL" With a subject of "CONFIG".
  568. Then, enter any of the commands listed below inside the Text of
  569. your mes- sage.  Remember to use one command per line.
  570. ADD <confnum>            Add a conference into the Qmail Door scanning
  571.                          list.  "YOURS" can also be added to the com-
  572.                          mand if the user wishes to receive messages
  573.                          only addressed them.  i.e. "ADD 1 YOURS"
  574. DROP <confnum>           Drop a conference from the Qmail Door scan-
  575.                          ning list.
  576. RESET <confnum> <value>  Resets a conference to a particular value.
  577.                          The user can use "HIGH-xxx" to set the con-
  578.                          ference to the highest message in the base.
  579. CITY <value>             Changes the "city" field in the user's
  580.                          PCBoard entry.
  581. PASSWord <value>         Changes the user's login passWord.
  582. BPHONE <value>           Business/data phone number
  583. HPHONE <value>           Home/voice phone number
  584. PCBEXPERT <on|off>       Turns the PCBoard expert mode ON or OFF.
  585. PCBPROT <value>          PCBoard File transfer protocol (A-Z).
  586. PAGELEN <value>          Set page length inside PCBoard.
  587. PCBCOMMENT <value>       Set user maintained comment.
  588. AUTOSTART <value>        Qmail Door autostart command.
  589. PROTOCOL <value>         Qmail Door File transfer protocol (A-Z).
  590. EXPERT <ON or OFF>       Turns the Qmail Door expert mode ON or OFF.
  591. MAXSIZE <value>          Maximum size of the user's .QWK packet (in
  592.                          Bytes)
  593. MAXNUMBER <value>        Maximum number of messages per conference.
  594.  
  595. [4.3.3]  MarkMail
  596.  
  597. Send a message addressed to "MARKMAIL" With the subject line saying:
  598.  
  599. ADD [value]         in the conference you want to add
  600. DROP                in the conference you want to drop
  601. YOUR [value]        in the conference you want only your mail sent
  602. YA [value]          in the conference you want only your mail + mail
  603.                     addressed to "ALL"
  604. FileS ON or OFF     in any conference to tell MarkMail whether to scan
  605.                     For new Files or not.
  606. BLTS ON or OFF      to turn on and off, respectively, of receiving
  607.                     bulletins.
  608. OWN ON or OFF       to turn on and off, respectively, of receiving
  609.                     messages you sent
  610. DELUXE ON or OFF    to turn on and off, respectively, of receiving
  611.                     DeLuxe menu
  612. LIMIT <size>        to set the maximum size of MESSAGES.DAT File can
  613.                     be, it cannot exceed what the Sysop has set up
  614.  
  615. An optional number can be added onto the commands "ADD", "YOUR",
  616. and "YA".  If this number is positive, then it will be treated as
  617. an abso- lute message number.  MarkMail will set your last read
  618. Pointer to that number.  If it is negative, MarkMail will set
  619. your last read Pointer to the highest minus that number.  For
  620. example: "ADD -50" will add the conference and set the last read
  621. Pointer to the highest in the confer- ence minus 50.
  622.  
  623. [4.3.4]  KMail
  624.  
  625. Send a private message addressed to "KMAIL" in the conference
  626. that you want to add, drop, or reset.  The commands are "ADD",
  627. "DROP", and "RESET #", respectively.  The "#" is the message
  628. number you want your last read Pointer in the conference be set
  629. to.
  630.  
  631. [4.3.5]  RoseMail
  632.  
  633. The RoseMail door allows configuration information be placed in
  634. either the subject line or message Text.  The message must be
  635. addressed to "ROSEMAIL".  For only one command, it can be placed
  636. in the subject line.  For more than one changes, the subject line
  637. must say "CONFIG" and each change be placed in the message Text.
  638. Every line should be left justified.  Valid commands are:
  639.  
  640. Command                                           Example
  641.  
  642. ADD <Conference> [<Message #>] [<Yours>]          ADD 2 -3 Y
  643. DROP <Conference>                                 DROP 2
  644. RESET <Conference> <Message #>                    RESET 12 5000
  645. PCBEXPERT <ON | OFF> - PCBoard expert mode        PCBEXPERT ON
  646. EXPERT <ON | OFF>    - RoseMail expert mode       EXPERT OFF
  647. PCBPROT <A - Z>      - PCBoard protocol           PCBPROT Z
  648. PROT <A - Z>         - RoseMail protocol          PROT G
  649. PAGELEN <Number>     - Page length                PAGELEN 20
  650. MAXSIZE <KBytes>     - Max packet size in Kb      MAXSIZE 100
  651. MAXNUMBER <max msgs/conference>                   MAXNUMBER 100
  652. JUMPSTART <Sequence or OFF>                       JUMPSTART D;Y;Q
  653. MAXPACKET <max msgs/packet>                       MAXPACKET 500
  654. AUTOSTART <Sequence or OFF> - same as jumpstart   AUTOSTART OFF
  655. OPT <##> <ON | OFF>  - set door option            OPT 2 OFF
  656.  
  657. [4.3.6]  Complete Mail Door
  658.  
  659. Send message to "CMPMAIL", the commands are "ADD" and "DROP".
  660. This message must be sent in the conference that you want to add
  661. or drop.
  662.  
  663. [4.4]  Turning off the echo flag
  664.  
  665. In order to send a non-echoed message (not send out to other
  666. BBSes), a user can enter "NE:" in front of the subject line.  The
  667. mail Program will strip this "NE:" and turn off the echo flag.
  668. This feature may not be offered in all mail doors.
  669.  
  670. [4.5]  Tag-lines
  671.  
  672. The most common format For a reader tag-line is:
  673.  
  674. [---
  675.  * My reader v1.00 * The rest of the tag-line.
  676.  
  677. The three dashes is called a tear-line.  The tag-line is appended
  678. to the end of the message and is usually one line only.  It is
  679. preferred that tag-lines conform to this format so that
  680. networking softwares such as QNet and RNet will not add another
  681. tearline to the message when they process it.
  682.  
  683. Softwares on FidoNet does not like mail readers adding a
  684. tear-line of their own, so if your mail reader offers a FidoNet
  685. mode, you will need to get rid of the tear-line.  Another item
  686. which differs between the FidoNet and PC-based networks is that
  687. FidoNet does not like extended ASCII Characters.  So your reader
  688. may want to strip high ASCII if the user has FidoNet mode on.
  689. Acceptable tag-line style, I believe, is just this:
  690.  
  691.  * My Reader v1.00 * The rest of the tag-line.
  692.  
  693. [5]  Net mail
  694.  
  695. I do not have complete information of net-mail Implementation
  696. using QWK-format.  Someone please fill me in the details.
  697.  
  698.                      -=-=-=-=-=-=-<>-=-=-=-=-=-=-
  699.  
  700. [A]  Credits and Contributions
  701.  
  702. Mark "Sparky" Herring, who originated the QWK-format.
  703.  
  704. Tim Farley, who started this documentation back in the summer of
  705. 1990. The general outline here is the work of Tim.  I filled in
  706. the blanks.
  707.  
  708. Jeffery Foy, who gave us the format For Microsoft single binary
  709. versus IEEE format.
  710.  
  711. Greg Hewgill, who (if I remember correctly) wrote the Turbo
  712. Pascal routines (included in here) to convert between MKS and TP
  713. LongInt.
  714. Dennis McCunney, who is the host of the Off-line conference on
  715. RIME, is very knowledgeable in off-line reading concept and
  716. Programs.  His goal is to have one reader that can read mail
  717. packet from any source.
  718.  
  719. All those who have been around the Off-line conferences on ILink
  720. (the oldest of the three I participate), RIME, and Intelec, who
  721. have pro- vided great help over the past two years.  The bulk of
  722. the information presented here are from messages in those
  723. conferences.  These people include, but are no limited to, the
  724. followings: Dane Beko, Joseph Carnage, Marcos Della, Joey Lizzi,
  725. Mark May, and Jim Smith.
  726.  
  727. [B]  Sample Turbo Pascal and C code
  728.  
  729. Here are a few routines in Turbo Pascal and C to convert
  730. Microsoft BASIC MKS format to usable IEEE long Integer.  These
  731. are collected over the networks and there is no guarantee that
  732. they will work For you!
  733.  
  734. Turbo Pascal (Greg Hewgill ?):
  735.  
  736. Type
  737.      bsingle = Array [0..3] of Byte;
  738.  
  739. { converts TP Real to Microsoft 4 Bytes single }
  740.  
  741. Procedure Real_to_msb (pReal : Real; Var b : bsingle);
  742. Var
  743.      r : Array [0 .. 5] of Byte Absolute pReal;
  744. begin
  745.      b [3] := r [0];
  746.      move (r [3], b [0], 3);
  747. end; { Procedure Real_to_msb }
  748.  
  749. { converts Microsoft 4 Bytes single to TP Real }
  750.  
  751. Function msb_to_Real(b : bsingle) : Real;
  752. Var
  753.      pReal : Real;
  754.      r : Array [0..5] of Byte Absolute pReal;
  755. begin
  756.      r [0] := b [3];
  757.      r [1] := 0;
  758.      r [2] := 0;
  759.      move (b [0], r [3], 3);
  760.      msb_to_Real := pReal;
  761. end; { Procedure msb_to_Real }
  762.  
  763. C (identify yourself if you originated this routine):
  764.  
  765. /* converts 4 Bytes Microsoft MKS format to long Integer */
  766.  
  767. unsigned long mbf_to_int (m1, m2, m3, exp)
  768. unsigned int m1, m2, m3, exp;
  769. {
  770.      return (((m1 + ((unsigned long) m2 << 8) + ((unsigned long) m3 <<
  771.      16)) | 0x800000L) >> (24 - (exp - 0x80)));
  772. }
  773.  
  774. Microsoft binary (by Jeffery Foy):
  775.  
  776.    31 - 24    23     22 - 0        <-- bit position
  777. +-----------------+----------+
  778. | exponent | sign | mantissa |
  779. +----------+------+----------+
  780.  
  781. IEEE (C/Pascal/etc.):
  782.  
  783.    31     30 - 23    22 - 0        <-- bit position
  784. +----------------------------+
  785. | sign | exponent | mantissa |
  786. +------+----------+----------+
  787.  
  788. In both cases, the sign is one bit, the exponent is 8 bits, and the
  789. mantissa is 23 bits.  You can Write your own, optimized, routine to
  790. convert between the two formats using the above bit layout.
  791.  
  792. [C]  Sample message
  793.  
  794. Here is a sample message in hex and ASCII format:
  795.  
  796. 019780  20 34 32 33 32 20 20 20 30 32 2D 31 35 2D 39 32   4232   02-15-92
  797. 019790  31 33 3A 34 35 52 49 43 48 41 52 44 20 42 4C 41  13:45RICharD BLA
  798. 0197A0  43 4B 42 55 52 4E 20 20 20 20 20 20 20 20 53 54  CKBURN        ST
  799. 0197B0  45 56 45 20 43 4F 4C 45 54 54 49 20 20 20 20 20  EVE COLETTI
  800. 0197C0  20 20 20 20 20 20 20 51 45 44 49 54 20 48 41 43         QEDIT HAC
  801. 0197D0  4B 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K
  802. 0197E0  20 20 20 20 20 20 20 20 20 20 20 20 34 30 33 36              4036
  803. 0197F0  20 20 20 20 37 20 20 20 20 20 E1 0A 01 00 00 20      7
  804. 019800  2A 20 49 6E 20 61 20 6D 65 73 73 61 67 65 20 64  * In a message d
  805. 019810  61 74 65 64 20 30 32 2D 30 39 2D 39 32 20 74 6F  ated 02-09-92 to
  806. 019820  20 53 74 65 76 65 20 43 6F 6C 65 74 74 69 2C 20   Steve Coletti,
  807. 019830  52 69 63 68 61 72 64 20 42 6C 61 63 6B 62 75 72  RiChard Blackbur
  808. 019840  6E 20 73 61 69 64 3A E3 E3 52 42 3E 53 43 20 AF  n said:
  809.  
  810. RB>SC
  811. 019850  20 65 64 69 74 6F 72 20 69 6E 20 74 68 65 20 28   editor in the (
  812. 019860  6D 61 69 6E 66 72 61 6D 65 29 20 56 4D 2F 43 4D  mainframe) VM/CM
  813. 019870  53 20 70 72 6F 64 75 63 74 20 6C 69 6E 65 20 69  S product line i
  814. [ etc. ]
  815. 019A00  6E 6F 74 20 61 20 44 6F 63 74 6F 72 2C 20 62 75  not a Doctor, bu
  816. 019A10  74 20 49 20 70 6C 61 79 20 6F 6E 65 20 61 74 20  t I play one at
  817. 019A20  74 68 65 20 48 6F 73 70 69 74 61 6C 2E E3 20 20  the Hospital.
  818.  
  819. 019A30  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
  820. 019A40  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
  821. 019A50  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
  822. 019A60  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
  823. 019A70  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
  824. 019A80  E3 50 43 52 65 6C 61 79 3A 4D 4F 4F 4E 44 4F 47
  825. PCRelay:MOONDOG
  826. 019A90  20 2D 3E 20 23 33 35 20 52 65 6C 61 79 4E 65 74   -> #35 RelayNet
  827. 019AA0  20 28 74 6D 29 E3 34 2E 31 30 20 20 20 20 20 20   (tm)
  828. 4.10
  829. 019AB0  20 20 20 20 20 20 20 20 20 48 55 42 4D 4F 4F 4E           HUBMOON
  830. 019AC0  2D 4D 6F 6F 6E 44 6F 67 20 42 42 53 2C 20 42 72  -MoonDog BBS, Br
  831. 019AD0  6F 6F 6B 6C 79 6E 2C 4E 59 20 37 31 38 20 36 39  ooklyn,NY 718 69
  832. 019AE0  32 2D 32 34 39 38 E3 20 20 20 20 20 20 20 20 20  2-2498
  833.  
  834. 019AF0  20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
  835.  
  836. [D]  Sample index File
  837.  
  838. Here is a sample index File in hex format:
  839.  
  840. 000000  00 00 28 87 19 00 00 30 87 19 00 00 38 87 19 00
  841. 000010  00 7E 87 19 00 00 07 88 19 00 00 0B 88 19 00 00
  842. 000020  0F 88 19 00 00 14 88 19 00 00 19 88 19 00 00 1E
  843. 000030  88 19 00 00 22 88 19 00 00 27 88 19 00 00 2C 88
  844. 000040  19 00 00 31 88 19 00 00 3B 88 19 00 00 40 88 19
  845. 000050  00 00 46 88 19 00 00 49 88 19 00 00 4D 88 19 00
  846. 000060  00 52 88 19 00 00 55 88 19 00 00 59 88 19 00 00
  847. 000070  60 88 19 00 00 66 88 19 00 00 70 88 19
  848.  
  849.  
  850.